Scripting
Getting Started
Documentation
Changelog
Privacy
Getting Started
Documentation
Changelog
Privacy

HealthUnit

The HealthUnit class provides an interface to construct and manipulate various units used in HealthKit. You can create basic units (e.g., grams, meters, liters), apply metric prefixes (e.g., milligrams, kilometers), and perform arithmetic operations like multiplication, division, exponentiation, and inversion.

Enum: HealthMetricPrefix

Represents metric prefixes applied to units:

Enum Value Symbol Example
none — gram()
milli m milligram
centi c centimeter
kilo k kilometer
mega M megajoule
micro µ microliter
nano n nanometer

Refer to the full enum for more supported prefixes.

1. Creating Units

Basic Units

1const weight = HealthUnit.gram()
2const distance = HealthUnit.meter()
3const energy = HealthUnit.kilocalorie()

Prefixed Units

1const mg = HealthUnit.gramUnit(HealthMetricPrefix.milli)
2const km = HealthUnit.meterUnit(HealthMetricPrefix.kilo)
3const mL = HealthUnit.literUnit(HealthMetricPrefix.milli)

Create from Unit String

1const unit = HealthUnit.fromString('kg')

2. Unit Arithmetic

Multiplication

1const meter = HealthUnit.meter()
2const second = HealthUnit.second()
3const speed = meter.divided(second) // meters per second

Division

1const bpm = HealthUnit.count().divided(HealthUnit.minute()) // beats per minute

Exponentiation

1const m2 = HealthUnit.meter().raisedToPower(HealthMetricPrefix.none) // square meters

Reciprocal

1const perLiter = HealthUnit.liter().reciprocal() // 1 per liter

3. Unit Properties

Property Type Description
unitString string String representation of the unit (e.g., "kg")
isNull boolean Indicates whether the unit is null/invalid

4. Using with HealthQuantitySample

Use HealthUnit when creating or reading quantity-based health samples.

Create a Sample

1const unit = HealthUnit.kilocalorie()
2
3const sample = HealthQuantitySample.create({
4  type: 'activeEnergyBurned',
5  startDate: new Date('2025-07-04T10:00:00'),
6  endDate: new Date('2025-07-04T10:30:00'),
7  value: 150,
8  unit: unit,
9})

Read Sample in Another Unit

1const valueInJoules = sample.quantityValue(HealthUnit.joule())

5. Common Units Overview

Category Example Methods
Weight gram(), pound(), ounce()
Length meter(), inch(), mile()
Volume liter(), fluidOunceUS()
Time second(), minute(), hour(), day()
Energy kilocalorie(), joule()
Temperature degreeCelsius(), kelvin()
Voltage volt(), voltUnit(prefix)
Light Intensity lux(), luxUnit(prefix)
Dimensionless count(), percent()
Sound Level decibelAWeightedSoundPressureLevel()

6. Example: Composite Unit Sample

1// steps per minute
2const unit = HealthUnit.count().divided(HealthUnit.minute())
3
4const stepSample = HealthQuantitySample.create({
5  type: 'stepCount',
6  startDate: new Date(),
7  endDate: new Date(),
8  value: 120,
9  unit: unit,
10})

7. Example: Parse from Unit String

1const unit = HealthUnit.fromString('g/mL')
2console.log(unit.unitString) // g/mL
3console.log(unit.isNull)     // false

Here is the official English documentation for the newly added Health.preferredUnits() method in the Scripting app’s Health module:

8. Health.preferredUnits() Method

Retrieves the user’s preferred display units for one or more HealthQuantityType entries. This is useful when presenting health data in a way that respects the system’s regional and user-specific settings (e.g., showing weight in kilograms vs pounds).

Method Signature

1function preferredUnits(
2  quantityTypes: HealthQuantityType[]
3): Promise<Record<HealthQuantityType, HealthUnit>>

Parameters

Name Type Description
quantityTypes HealthQuantityType[] An array of health quantity types (e.g., "bodyMass", "height").

Returns

A Promise that resolves to a mapping object (Record) where each key is a HealthQuantityType, and each value is a corresponding HealthUnit representing the user's preferred unit for that type.

Throws

An error if the system fails to determine the preferred units for the given quantity types.

Example

1const types: HealthQuantityType[] = ["bodyMass", "height", "dietaryEnergyConsumed"]
2
3const preferred = await Health.preferredUnits(types)
4
5const bodyMassUnit = preferred["bodyMass"]         // e.g., kilograms or pounds
6const heightUnit = preferred["height"]             // e.g., meters or inches
7const energyUnit = preferred["dietaryEnergyConsumed"] // e.g., kilocalories
8
9console.log("Preferred units:")
10console.log("Weight:", bodyMassUnit)
11console.log("Height:", heightUnit)
12console.log("Energy:", energyUnit)

Usage Notes

  • Preferred units may vary across devices depending on locale and user Health app settings.
  • Always call this method before displaying health data in the UI if you want to respect the user’s expectations.
  • For unsupported or unknown quantity types, the result may omit that key.
Outline